mAC3dec Read Me 1.6.3

by   L u k i f e r   :   lukifer@mail.com

Description
. . .
mAC3dec is an AC-3 audio decoder for the Macintosh, used to decode the AC-3 audio used on DVDs and convert to AIFF, MP3, or QuickTime. mAC3dec can also read QuickTime files, AIFFs, WAVs, MP3s, Audio CD tracks, and more. This program, including all source code, is hosted by sourceforge at sourceforge.net/projects/mac3dec.

Requirements
. . .
Classic:	MacOS 8.6 or later, CarbonLib 1.0.4 (1.6 recommended), QuickTime 4 (5.0.2 recommended)
OS X:	OS 10.0.4 (10.3 recommended), QuickTime 5 (6 recommended)

Shameless Self Promotion
. . .
If you like mAC3dec, please make a donation using the link in the About mAC3dec dialog box.

Do it now! Now now now!

Disclaimer
. . .
By using this program, you agree to use it in a responsible and legal manner.  A great deal of AC-3 audio content comes from DVDs which are heavily restricted by copyright law and draconian legislation such as the Digital Millennium Copyright Act.  By using this program, you agree to act in accordance with these laws, regardless of how ridiculous or unconsitutional they may be.  Anyone found to be using this program in violation of such laws will be scolded harshly and forced to go to bed without dinner.

How to Use
. . .
First, you must acquire AC-3 files; to extract them from a DVD (assuming you have verified with the proper authorities that you are legally authorized to do so) you can use DVD Extractor, YADE or Fair Use for OS 8.x/9.x, or OSEx for (you guessed it) OS X. To extract an AC-3 from a VOB (Video Object file), try bbDEMUX (sourceforge.net/projects/macbbdemux). To extract an AC-3 soundtrack from an AVI (such as a DivX file), use DivX Doctor 2.1 (doctor.3ivx.com).

Add any AC-3 (or QuickTime) files you wish to decode by selecting "Add AC-3..." from the File menu, or by just dragging them onto the decode window. Once all your files are loaded, hit "Start" to begin the decode.  By default, the decoded files will show up in the same folder as the input files. You can hit Command-Period (.) or the "Cancel" button if you change your mind.

If the program encounters an AC-3 it has problems with, you can select the problem file(s) in the batch list and choose "Fix AC-3..." from the Decode menu, which may correct the errors in the file.

Options
. . .
Format: The type of file you wish to create: AIFF, WAV, PCM (raw audio), MP3, or MOV (QuickTime).

Sample Rate: Audio settings of output file; 44.1 kHz is recommended. To maintain maximum sound fidelity, choose 48 kHz; however, note that this will still play back on most Macs and PCs at 44.1 kHz, and require more CPU power to play back. To specify the exact audio settings, use "Custom".

MP3 Options: MP3 encoder settings.

MOV Options: QuickTime encoder settings.

Normalize: Maximizes the volume on a given AC-3 or QuickTime file without overdriving; highly recommended.

...Globally: Normalizes all files, and brings them all to the same relative volume level.

Split Channels: Create a separate file for each AC-3 channel. Keep off unless you have a good reason.

Same Destination As Input: Put output files in the same folder as the input, rather than asking.

Auto-Decode: Begins decoding as soon as files are added; useful for drag and drop operation.

Quit When Done: Does what it says. Also useful for drag and drop operation.

Dynamic Range Compression: Makes loud sounds softer and soft sounds louder; recommended on.

Dolby Downmixing: Attempts to preserve surround sound in Dolby Stereo; recommended on.

Use LAME Resampling: Uses LAME's resampling for MP3s (rather than QuickTime).

Normalize To: How loud audio will be after normalizing; reduce this value if there is clipping (popping noises).

Default: Return normalization value to default (95%, recommended).

MP3 Options
. . .
Quality: "High" will give better quality and take longer to encode, while "Low" will be quick but will sound worse. Stick to "High" as much as possible.

Method: Type of bitrate tracking. CBR (Contstant Bit Rate) maintains a consistent bitrate throughout the file. ABR (Average Bit Rate) varies the bitrate as needed, giving better quality, and attempts to maintain the given average rate. VBR (Variable Bit Rate) lets the encoder decide on the bitrate, depending on the VBR quality chosen.

Minimum/Maximum Bitrate: Set a floor and/or ceiling on the bitrate so that ABR/VBR can't go above or below a certain level of quality. Make sure not to set the minimum too high or the maximum too low, or you may end up with a poorly encoded file.

Use "--nspsytune": Use an alternative psychoachoustic model; may increase audio quality. However, this option is experimental, and may be buggy.

MP3 Encoding Tips
. . .
- Use ABR or VBR whenever possible.

- When using VBR, keep the maximum bitrate as high as possible.

- Clipping throws LAME's VBR encoder for a loop, so if MP3 encoding is giving an error message, try turning on normalization, or turning down the normalization value in Preferences.

- Some lower bitrates will not work with higher sample rates, and vice versa; if you're getting MP3 encoding error messages, try changing your bitrate settings around.

Known Bugs
. . .
- There appears to be a minor compatibility problem between LAME and QuickTime; QuickTime will "stretch" the length of LAME-encoded MP3s by roughly 0.1-0.2%. I have informed both Apple and the LAME developers of this, and have not yet recieved any response. When working with audio and video together, this can affect sync; the work-around is to use Add Scaled within QuickTime to add the video track to match the audio. You can also use the application Sync-Hole (nsorscher.home.attbi.com/apps/Sync.html) to edit the sync manually.

- When decoding VBR MP3s, the last half second or so often gets truncated. If this audio matters (or the difference in length will throw off track scaling), the workaround is to use QuickTime Pro to export to AIFF, then drop the AIFF onto mAC3dec. This problem will be fixed ASAP (assuming it's not on QuickTime's end, since this bug shows up even in some of Apple's sample code).

- AIFF "Custom" does not work with MetaSound, MetaVoice, and QDesignMusic 2, at least as far as I've tested. This appears to be something particular to these codecs that I can't do anything about. Use the MOV format instead.

- Due to a combination of difficulty and laziness, MP3/QT encoding, normalization, QuickTime decoding and resampling will work with channel splitting. Sorry.

- Normalization of QuickTime files may be slow and inaccurate; use with caution and skepticism.

Version History
. . .
1.6.3:
Added:
     - Option to adjust the normalization value.
     - Warning when VOB files are added.
     - Now saves all files at once when choosing destination. (This really should have been done long ago.)

Fixed:
      - Made Dynamic Range Compression and Dolby Stereo the defaults.
      - Preferences bugs.

1.6.2:
Added:
      - Pause button and other interface tweaks.
      - Option to quit when finished.
      - Option to ask before canceling.
      - Updated to LAME 3.96.

Fixed:
      - Long-named input files now give sane file names for output.
      - Corrected Read Me regarding Dyanamic Range Compression.

Removed:
      - Altivec option, as no Altivec code is in use right now anyway.

1.6.1:
Added:
      - Selecting an AC-3 now displays its approximated audio length.
      - Updated to LAME 3.95.

1.6:
Fixed:
      - AC-3 fixing now actually usable, though generally obsolete due to a52lib's improved header seeking.
      - Channel splitting should be less buggy.
      - Fixed a bug that could cause loss of samples near the end of a file.
      - OS X icon is now native.
      - Many other minor changes and fixes.

Added:
      - Updated to a52dec 0.7.4, including support for Dolby Surround Stereo and dynamic range compression.
      - Added WAV output.
      - Pause menu item.
      - Option to disable progress bar, which may increase performance on OS X.
      - Recompiled under CodeWarrior 8.3.

Removed:
      - VOB parsing currently removed due to bugs; may be reimplemented in the future. Use bbDEMUX.
      - Channel splitting may no longer be resampled or encoded; to do so is pretty unnecessary and very difficult.
      - Auto-fixing is now obsolete.

1.5.2:
Fixed:
      - Yields the processor less while application is active.

1.5.1:
Fixed:
      - Should now work correctly on OS 8.6 and OS 9 (assuming CarbonLib is installed).
      - Cleaned up file naming a bit.

1.5:
Fixed:
      - Event handling bug that made the app hog the processor.
      - OS X icon is a little prettier.
      - A few small bugs.
      - Altivec bug fixed; one application now works on both G4 and pre-G4 chips.

Added:
      - Added experimental QuickTime decoding, handling such formats as AIFF, WAV, MP3, and more!
      - Recompiled under CodeWarrior 7.

1.4:
Fixed:
      - Problems with sound quality.
      - Nasty freezing bug.
      - MP3 encoding bug while using --nspsytune with VBR.
      - Problems with VBR header tag.
      - Visual GUI bug with the batch list.
      - Minor Altivec bug.
      - Code is generally one thousand percent cleaner.

Added:
      - Updated LAME sources to 3.91.
      - Can now read files larger than 2G (which only really matters for VOBs).
      - Now handles output AIFFs over 2G by creating a new file.
      - Interface tweaks.

1.3:
Fixed:
      - Cleaned up IMDCT routines; may give a very minor speed boost.
      - Dumb bug that chopped off the final frame.  All decodes will now be the correct length.
      - Another dumb bug that left the remainder of the resampling buffer unwritten.
      - Normalization bug; normalizing will be a little slower, but should sound much better.

Added:
      - Updated LAME to latest version (3.89) and integrated into app; now decodes straight to MP3.
      - Global normalization, so that a full movie or album may all be decoded at the same volume.
      - Experimental VOB parsing; may be buggy, so don't be shocked if crashes or The Apocalypse ensue.
      - Further Altivec acceleration, giving a 10-40% speed boost on G4s.
      - Increased memory requirements to accomodate buffers for LAME, Altivec, and VOB parsing.

1.2:
Fixed:
      - Windowing and controls should play nicer now.
      - Removed live resizing, due to its pain-in-the-ass-ness.
      - Altivec now works, though the benefits are minuscule for the time being.
      - Minor but nifty interface tweaks.
      - Lots and lots and lots of little things.

Added:
      - Rewritten to be entirely object-oriented, and much cleaner.
      - Removed Adjust Gain option in favor of true normalization.  It's better, trust me.
      - MP3 encoding, via LAME 3.70!  Requires LAME Shared Library, to which source is available.
      - Updated decoding routines from latest ac3dec, giving roughly a 25% speed boost.
      - LFE works for channel splitting, but is disabled for stereo until I perfect the downmixing routines.
      - Scripting dictionary has been removed until I can replace it with a better one.

1.1:
Fixed:
      - Internal code revamp.
      - Will no longer attempt to fix a "broken" AC-3 more than once if it continues to have problems.
      - Fixed a bug that caused the end of a previous decode to be tacked onto the beginning of the next*.
      - Fixed a rematrixing bug.
      - Fixed a Gestalt bug that did not properly identify the presence of AltiVec.

             *Why did nobody tell me about this?!?!?!?

Added:
      - Batch processing, allowing several AC-3s to be decoded at once.
      - Full GUI and decode window, which supports drag-and-drop.
      - More feedback during the decode process, including AC-3 file details and time remaining.
      - Channel Split option, decodes up to 5 channels to separate files (LFE currently not supported).
      - More options in preferences.
      - Live window dragging/resizing! Whee!
      - Allows decoding to raw (headerless) PCM (Pulse Code Modulation) audio.
      - Minor Altivec (G4) acceleration; however, this is disabled due to a bug in CodeWarrior.
      - Slightly better scriptability, and an included AC-3 -> MP3 script.

1.0.1:
Fixed:
      - Should now run correctly on OS X.
      - Increased disk input buffer, because I can. :)  May increase speed a bit.
      - Made "Output Destination: Same as Input" the default choice: much easier to use, IMHO.

Added:
      - Gain adjustment for low-volume AC-3s.  Be careful, the audio will get distorted if you go too far!

1.0:
Fixed:
      - Version now REALLY set correctly in resource fork. (Doh!)
      - Fixed some file I/O stuff: now only writes a file if it is a working AIFF.
      - Now closes an input AC-3 file when it is finished with it. (sorry, Jeff!)
      - Now tells you what file you're decoding.
      - Fixed icon mask for 8-bit icon; should look a little less butt-ugly.
      - Dialog box updates and file I/O occur less frequently, which should increase overall speed.
      - Other marginal speed-ups.

Added:
      - Fully Carbon compliant, running natively on OS X!
      - "Custom" audio is now working.  Not all sound codecs are compatible, but most work.  (See above)
      - Limited AppleScript support.  Details may found with the program source code.

0.9.2:
Fixed:
      - Elusive "hanging decode" bug should now be gone.  (Kudos to Squirrel for fixing this!)
      - Fixed a small bug with the AC-3 fixer that caused the file to be too long.
      - Fixed a very small bug with preferences that would cause the program to "forget" changes.
      - Progress bar is now truly accurate.

Added:
      - New option to save the output file to the same folder as the input file automatically.
      - A few minor graphical tweaks.
      - Reluctantly switched to Navigation Services in preparation for Carbon.
      - Several other internal changes in preparation for Carbon.

0.9.1:
Fixed:
      - 44.1 kHz downsampling lost about .01 seconds of audio every 5 minutes; should now be perfect.
      - Bytes Written now updates while the app is in the background.

Added:
      - Implemented experimental AC-3 fixing.
      - Output file name now matches input file name.
      - May be marginally faster.

0.9:
Fixed:
      - Fixed a memory leak that would have crashed the program after enough decodes.
      - Should now handle update events properly.
      - Version now set correctly in resource fork.
      - Lots more little things

Added:
      - Now multitasks fully; no more waiting idly during decodes.
      - Decodes straight to the Mac's native 44.1 kHz audio; 48 kHz decoding still available as an option.
      - Added preferences menu option to determine choice of audio output.
      - Handles basic Apple Events: AC-3s may be dragged-n-dropped or double-clicked to decode.
    	 - Slightly improved application icon and vastly improved file icon. (Thanks again, eevyl!)

0.8:
Fixed:
      - Now replaces files OK when saving.
      - Multitasks to allow apps in background to keep running.
      - Should no longer crash when encountering bad AC-3s (at least, not as much).
      - Output AIFF should still be playable even after a canceled decode.
      - Found that the first decode went OK, but subsequent ones bailed out early; now fixed.
      - Fixed creator code (mAC3), which I had accidentally switched with the file type (AC-3).
      - Countless other minor bugs.

Added:
      - Source code is now available with this version.
      - Decoding process can be killed by pressing Cancel or Command-. (Period).
      - Appearance Manager-friendly.
      - Decoding progress bar.
      - Added application icon and a tentative file icon (Thanks to eevyl for the great-looking icon!)

0.7:
Works.  Doesn't do much else.  Buggy as hell.